Copyright: Robert Alan Wright


Contents

Introduction to Visual Diff and Merge

Features of Version 1.0

Viewing File Differences

Merging Two Versions of a File

Setup Properties and Display Options

Registration and Author Information

User License (Please Read)


Introduction to Visual Diff and Merge

Visual Diff and Merge is a software developer's tool for finding and displaying the differences between two versions of a source file, and for merging separate changes made to the same source during concurrent development. It is meant to be useful by itself, or in conjunction with a software configuration management tool which can automatically detect conflicting source file changes during a "check-in" or related operation.

The graphical interface of this tool utilizes color and symbols to distinguish changes by type or by origin, and this use of color allows the merge interface to display all text in a single window, instead of utilizing three or more windows as do some other merge tools.  The merge function also attempts to perform an accurate merge prior to displaying the result, thus reducing the user's task to verifying correctness of the merge and resolving any conflicts (which are automatically detected and indicated).

Visual Diff and Merge is a shareware product. Please the read the license and registration information.

Please note: Most of the colors used by VDIFMRG are user-selectable. Please take advantage of this feature if you prefer a color scheme other than the default. Also note that the default colors may be less attractive in 256 color mode, and higher color modes are prefered.


Features of Version 1.0

Version 1.0

This is the initial version of VDIFMRG. It is safe to assume that a number of bugs will be found (and hopefully reported). Subsequent versions will be corrected and improved as the response dictates.

This version of VDIFMRG has the following features and functions:

Diff

•	Displays the differences between two versions of a file.

•	File differences are displayed utilizing colors and symbols which indicate the type of diff (deletion, addition, or change).

•	Search feature:  A menu item and toolbar button are provided for scrolling to the next difference in the file.

•	Supports an option to ignore leading and trailing whitespace during line comparisons.

Merge

•	Determines the changes which have been made to two separately created versions of a file based on their common predecessor.

•	Merges the two sets of changes in order to create a new version incorporating both.

•	Conflicting changes (i.e. different changes to the same area of the file) are detected and indicated.

•	The merged output is labelled such that the areas changed since the common predecessor are distinguishable as to type as well as origin (i.e. in which version they were made).

•	Changed areas of the file are also hilighted using one of two coloring schemes: (1) according to the type of change, or (2) according to the file in which the change occurred.

•	Areas of text which were present in the original file but which have been deleted and/or changed in one or both versions of the file are marked as "excluded", and are colored so as to indicate that they will not be included in the result.

•	Areas of the merged text may be selected in order to perform one of the following operations:

(1) Toggle the exclusion state of the selected lines (this allows the user to choose lines which should be eliminated from the merge result, or to include lines in the result which were previously marked for exclusion.)

(2) Edit the selected lines using a text editing window. Edited lines will then replace the selection in the merge result.

•	Search features:  In addition to the diff search feature, a menu item and toolbar button are provided for scrolling to the next conflict in the file.

•	A toggle is provided to determine whether or not excluded text is displayed. (Note that it is necessary to display exclusions if any such text needs to be selected for re-inclusion in the output.)

Setup and Miscellaneous

•	Font selection: The user is permitted to select a fixed-width typeface as well as a character size.

•	Color selection: Several different colors are used for each of the display modes. The user is permitted to select custom colors for each effect.

•	Tab spacing: The spacing between tab stops may be selected.

•	Tmp directory: The user may specify the directory to be used for temporary files.

•	Command line arguments: Either two or three file name arguments may be included in the run command. If two are included, then a diff operation is performed on the two files. Three files invoke a merge in which the first file is assumed to be the common predecessor. One optional argument, -b, may also be included. This option has the effect of ignoring leading and trailing whitespace during line comparisons.

Known Bugs and Limitations

•	Output size: If the computed result is longer than the MFC ScrollView Class can handle, you will not be able to scroll through all of the text. I have not found any adequate workaround for this problem.


Viewing File Differences

This operation allows you to view the differences between two versions of a file. The output is generated by merging the text of both versions, with the changes (between the first version of the file and the second)  being indicated both by a symbol in the left margin of the display, as well by background and text coloring specific to the type of change.

The two files (or versions of one file) may be specified in two ways. The paths may be placed on the command line, or the diff operation may be selected from the operations menu or by pressing the diff toolbar button. An option may also be specified to cause leading and trailing whitespace to be ignored during line comparisons (-b on the command line).

Once the differences have been displayed, the user may scroll rapidly to each change using the "next diff" menu option or the corresponding toolbar button.


Merging Separately Changed Versions of a File

Introduction to the Merge Operation.

This operation is designed to facilitate the merging of separate changes to the same file which occurred as a consequence of parallel or concurrent development. Typically, a configuration management tool may detect situations in which a file to be checked into a repository has been modified and checked-in elsewhere since the changed copy was made.

In order to perform a merge, three versions of the file are required: the two changed versions, and a common predecessor from which both of the two changed versions are derived. The three versions may be given either on the command line (with the predecessor first), or using the merge operation dialog.

The Merge Algorithm.

The merge operation is straightforward: First the changes between each file and the common predecessor are determined using the diff function. Then the two files are completely merged, such that all changes in both versions are applied to the output. If any of the changes overlap, thus making it unlikely that  the merge algorithm can produce a correct result, the two changes are combined heuristically, and then flagged as a conflict. Note that even non-conflicting changes may not be merged in a sensible or correct way, but  the presumption is that non-overlapping changes in the two files do not conflict.  One other thing to note is that text which is deleted or changed in either file is also included in the output, but is marked as "excluded", meaning that it will not be included in the output, but will be shown so the user is aware of what has changed.

Merge Output Display Format.

The merge output shows several things. First, all areas of text changed in either file are indicated by a change in background color. There are two modes for this aspect of the display: (1) color by type, or (2) color by source. The former is the method used for diff output display, in which the type of change (e.g. deletion, addition, change from/to) is used to select a color. The latter simply colors the changes according to where they orginated (i.e. the first file, the second file, or both).

A second thing included in the output are margin symbols to indicate both the type of change as well as the source of the change. These margin symbols are thus redundant with the coloring schemes described above. The symbols "<", ">", and "=" are used to indicate whether the change originated from the first, second, or both versions, respectively. In addition, the symbols "-", "+", "c", and "C" are used to indicate a deletion, addition, change-from, and change-to, repsectively.

The third thing the default output shows is whether or not text has been marked for exclusion. This will usually be shown by the normally black text being greyed-out or lightened. Note that after the merge output has been presented, the user will be able to alter the exclusion state of any text.

A last, but important, aspect of the default merge output is the indication of conflicts. These are shown by changing the normally grey margin bar to a bright red.

After the default output has been presented, two user operations may alter the appearance of the text. The first is line selection, which is performed with the left button of the mouse. When a line or range of lines is selected, its background color will be altered to reflect the selection state. Operations which may be performed on selected text are described below.

The second operation is editing of a (range of) selected line(s). This operation is discussed below, but the result is that some of the default output lines are replaced by user-edited lines. When this is done, the user edits are show in a different color, and a special symbol, "E", is displayed in the margin.

How to Complete a Merge.

To successfully merge the two sets of changes, the following steps should be performed:

•	Invoke the merge, which will then display the default merged output.

•	Search for conflicts, and correct the merge in these regions in one of two ways described below. (The "Next Conflict" menu option or toolbar button may be used to accelerate this process.)

•	Rescan all diffs to verify correct operation of the merge. (The "Next Diff" menu option or toolbar button may be used to accelerate this process.) Make any need changes as was done for conflicts.

•	Save the output to a file. The "Save(as)" menu option and toolbar buttons may be used for this.

Altering the Default Merge Result.

Two ways are provided to change the merge result computed by VDIFMRG. The first is by toggling the exclusion state of one or more selected lines. This allows the user to mark lines for exclusion from the output which the merge algorithm had chosen to include, or vice versa. This operation is available on a menu or via a toolbar button.

The second way to alter the pre-computed result is to select a range of lines and invoke the edit operation (via menu or toolbar.)  When edit is invoked on a range of lines, all of the selected lines (even those marked for exlcusion),  are transfered to an edit view which becomes active. The user then may edit the text using familiar editing commands (e.g. those available in the notepad). When editing is complete, the user may decide either to discard the edits, or to replace the originally selected lines in the merged text with the edited lines. If the latter is done the edited lines will be clearly indicated as such in the display with both a special margin symbol ("E") as well as a distinct color.


Setup Properties and Display Options

Setup Options.

The VDIFMRG setup dialog, which may be invoked via a menu option or toolbar button,  allows the user to select the following display properties:

Custom Colors: Most of the colors used to display diff and merge output may be altered by the user. To do this, simply click the left mouse mouse while pointing at the sample block of the color to be changed.

Text font: The font used may also be changed. Both the typeface and the size may be altered. Note that for best results, a fixed-width font should be used.

Tab Spacing: The number of spaces between tab stops may be selected so that displayed output matches the source format. Values between 1 and 8 are permitted.

Window Size: The size of the application frame window may be specified. Normally, the size would be set by resizing the window with the mouse. The current size is displayed in setup primarily to indicate the value which will be saved in the .ini file should the "save" operation be invoked (see below).

Temporary Files Directory: A directory may be chosen for storing temporary files generated by the diff engine. The default is "c:\tmp". Note that an existing directory must be specified or diff and merge operations may fail.

Line Window:  This parameter affects the performance of the diff engine when comparing large files. In particular, two lines are not compared if they are farther apart than this distance. Thus all movement of lines is assumed to cover less distance than the window. Choosing a large value (> 250)  is safe for files of less than 500 lines or so, but large files may take a long time to compare.

Work Harder:  Setting this checkbox parameter to true (checked) will cause the diff engine to try harder to minimize the number of diffs found by altering the way changed lines are grouped. This also slows down the diff somewhat.

Setup Dialog Operations.

The following operations are provided as buttons on the Setup Dialog:

OK: This button has the effect of applying all changes (see apply) and closing the dialog. Changes are not automatically saved to the vdifmrg.ini file (see Save).

Cancel: This buttons performs a restore operation (see below), and then closes the dialog.

Apply: This operation causes all selected changes to be applied immediately to the merge display. (The effect of these changes may not be apparent if no appropriate output is currently present in the display.) This operation is not persistent unless the OK and/or Save buttons are also used. The Cancel and Restore buttons may be used to revert to the settings that were in effect at the time the dialog was opened.

Restore: Reverts to, but does no apply, the changes which were in effect at the time the dialog was opened.

Save: Saves the currently selected properties (and applies them if not already done) to the vdifmrg.ini file.

Reread .INI: Reads the vdifmrg.ini file (located in the Windows directory) and sets all property values as recorded there. Does not apply these values.


Registration and Author Information

User Registration.

This software is shareware, and you are strongly encouraged to register your copy to encourage further work of this kind. Please feel free to evaluate the product for a period of up to 60 days. Beyond that period, use of the software

is in violation of the license. Note that support  will be available only to registered users.

The registration fees are as follows:

Single user:	$10

10 or more:	$5 per user

Site license:	$1000 (unlimited right to use at one site)

Source and distribution licenses must be negotiated with the author.

Please make checks payable to Robert Alan Wright, and send to:

Robert Alan Wright

Alberta Software

1194 Johnson Ave.

San Jose, CA 95129

Distributor and Vendor Policies.

The exclusive copyright for this software is held by Alberta Software, and the following restrictions apply to anyone wishing to distribute or sell copies. Note this is not free software, and should not be represented as such.

The original .zip file containing this software and documentation may be distributed by placement on publically or privately accessible ftp or bbs sites so long as said original file is unmodified.

Other than as specified above, no one may distribute or sell this software for profit or otherwise without a prior written agreement with Robert Alan Wright and Alberta Software. Such agreements will generally incur a fee or royalty payment, and will be required for inclusion in a commercial software package or on a CD-ROM (or any other medium) created for distributing or selling a shareware collection.

Support Policy.

Support will be available via e-mail only. Any registered user who submits a bug report (including all needed accompanying files and procedures to reproduce the bug) will be entitled to receive (via e-mail or ftp) an updated version of the software when and if the bug is found and corrected, and such fix is incorporated into a new version of the software. While every effort will be made to fix all reported problems in a timely fashion, no timeframes can be given for completing such changes nor distributing the corrected software. In general, new versions of the software will only be distributed after a number of improvements have been accumulated. The author reserves the right of judgement as to what constitutes correct behavior of the software.

Enhanced, corrected, or otherwise improved versions of the software will not be automatically distributed directly to registered users other than in the case indicated above. Instead, the new version will supersede any previous ones on the authors chosen distribution channels, and notice of the new version may be sent to currently registered users if the author deems it appropriate.

In addition to bug reports, enhancement ideas and requests will also be appreciated.

The author may be reached via e-mail at:

alan@netgate.net

 or

alan@netcom.com


User License (Please Read)

User License Agreement.

This is a legal agreement between you and Alberta Software. By using the software you are agreeing to be bound by the terms of this agreement.

Alberta Software software license

1. Grant of license. Alberta Software grants to you the right to use one copy of the software program Visual Diff and Merge (the "SOFTWARE") on a single computer. The software is in "use" on a computer when it is loaded into the temporary memory (i.e., RAM) or installed into the permanent memory (e.g., hard disk, CD-ROM, or other storage device) of that computer. You may make the SOFTWARE available on a network, or  otherwise use it on more than one computer or computer terminal at the same time, only if each user agrees to the terms and conditions of this license.

2. Copyright. The software is owned by Alberta Software and is protected

by United States copyright laws and international treaty provisions. Therefore, you must treat the SOFTWARE like any other copyrighted material (e.g., a book or musical recording) except that you may (a) transfer the SOFTWARE to a single hard disk provided you keep the original solely for backup or archival purposes and (b) distribute the file VDIFMRG.ZIP, and only file VDIFMRG.ZIP, containing the Shareware edition of the SOFTWARE, under conditions of the Shareware edition of the Alberta Software license agreement. You may not copy the written materials accompanying the SOFTWARE. You may not rent or lease the SOFTWARE, but you may transfer the SOFTWARE and accompanying written materials on a permanent basis provided you retain no copies and the recipient agrees to the terms of this Agreement. If the SOFTWARE is an update or has been updated, any transfer must include the most recent update and all prior versions.

3. Distribution. You are allowed to make as many copies of the file VDIFMRG.ZIP containing the Shareware version of the SOFTWARE as you wish; give exact copies of this file to anyone; and distribute this file in its unmodified form, as long as it is not distributed for profit (handling fees up to $5.00 ok). Please refer to the file LICENSE.TXT in the file VDIFMRG.ZIP containing the Shareware edition of the license agreement for conditions of the distribution of the Shareware edition of the SOFTWARE.

4. Other restrictions. You may not reverse engineer, decompile, or disassemble the SOFTWARE. You are not allowed to make any modifications to, or to create derivative works from any of the files that are used in this software. This includes all the executable, help, installation, and readme files, as well as graphics images.

DISCLAIMER OF WARRANTY

The SOFTWARE (including instructions for its use) is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. Alberta Software further DISCLAIMS ALL IMPLIED WARRANTIES INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR OF FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK ARISING OUT OF THE USE OR PERFORMANCE OF THE SOFTWARE AND DOCUMENTATION REMAINS WITH YOU.

IN NO EVENT SHALL ALBERTA SOFTWARE, ITS AUTHORS, OR ANYONE ELSE INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THE SOFTWARE BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE OR DOCUMENTATION, EVEN IF ALBERTA SOFTWARE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES/COUNTRIES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.